<html>

<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>cdb 3.1</title>
<link HREF="http://drh.home.dyndns.org/" REV="made" TITLE="David R. Hanson">
</head>

<body>

<h1>cdb 3.1</h1>

<p>This hierarchy holds the implementation of cdb version 3.1, the debugger described in
D. R. Hanson,
&lsquo;A Machine-Independent Debugger&mdash;Revisited&rsquo;,
<cite>Software&mdash;Practice and Experience</cite> <strong>29</strong> (10), 849-862, Aug. 1999; 
this paper is available at
<a href="http://storage.webhop.net/documents/cdb3.pdf">http://storage.webhop.net/documents/cdb3.pdf</a>.</p>

<p>The initial version of cdb is described in
D. R. Hanson and M. Raghavachari,
&lsquo;A Machine-Independent Debugger&rsquo;,
<cite>Software&mdash;Practice and Experience</cite> <strong>26</strong> (11), 1277-1299, 11/96,
which is available at
<a href="http://storage.webhop.net/documents/cdb.pdf">http://storage.webhop.net/documents/cdb.pdf</a>.</p>

<p>For more information about cdb, visit <a
href="http://www.cs.princeton.edu/software/lcc/cdb/">http://www.cs.princeton.edu/software/lcc/cdb/</a>.</p>

<h2>Contents</h2>

<dl>
  <dt><a href="readme.html"><code>readme.html</code></a></dt>
  <dd>this file.</dd>
  <dt><a href="makefile"><code>makefile</code></a></dt>
  <dd><code>make</code> instructions for building cdb.</dd>
  <dt><code>lookup.[ch] wf.c</code></dt>
  <dd>sample program described in &lsquo;A Machine-Independent Debugger&rsquo;.</dd>
  <dt><code><a href="src">src</a>/*.[ch]</code></dt>
  <dd>source code for cdb, the nub, the RPC code, the prelinker script, and the symbol-table
    emitter additions to lcc.</dd>
  <dt><code><a href="etc">etc</a>/*.c</code></dt>
  <dd>lcc driver back ends modified to support the -Wo-g4 option.</dd>
  <dt><code>startup/{*.o,*.obj}</code></dt>
  <dd>platform-specific startup code modified to start the nub. Only startup/solaris.o,
    startup/linux.o, and startup/win32.obj have been tested.</dd>
</dl>

<h2>Differences</h2>

<p>&lsquo;A Machine-Independent Debugger&rsquo; describes the initial version of cdb. <a
href="http://www.cs.princeton.edu/software/lcc/cdb/2.x.html">http://www.cs.princeton.edu/software/lcc/cdb/2.x.html</a>
describes the differences between the initial version and version 2.2. The list below
summarizes the differences between version 3.1 and cdb 2.2. For all the details, see
&lsquo;A Machine-Independent Debugger&mdash;Revisited&rsquo;.</p>

<p>This version works only with lcc 4.1, and it requires the ASDL generator, asdlGen (<a
href="http://sourceforge.net/projects/asdl/">http://sourceforge.net/projects/asdl/</a>),
and the C Interfaces and Implementations (CII) library (<a
href="http://www.cs.princeton.edu/software/cii/">http://www.cs.princeton.edu/software/cii/</a>).</p>

<p>In the two-process version, cdb is the server and the target (the program being
debugged) is the client. <a href="src/server.c"><code>src/server.c</code></a> is the
server side of the RPC channel and <a href="src/client.c"><code>src/client.c</code></a> is
the client side. (These roles are reversed in Table 1 and Figure 6 in the initial cdb
paper.) cdb can run on a different machine than the target, but the machines must have the
same type metrics and endianness.</p>

<p>All strings, types, and symbol-table entries are stored in an ASDL &lsquo;pickle&rsquo;,
which is named <em>X</em><code>.pickle</code>, where <em>X</em> is the unique module
identifier. <a href="src/sym.asdl"><code>src/sym.asdl</code></a> defines the relevant data
structures. cdb reads pickles when a client attaches.</p>

<p>Modules hold only an unique module identifier and a pointer to an array of addresses of
globals and statics, which is stored in read-only memory.</p>

<p><code>_Nub_bp</code> takes only one argument, the index of the stopping point i, and
switches to cdb if <code>_Nub_bpflags[i]</code> is nonzero. cdb determines if a breakpoint
<code>i</code> is set in the module that caused the switch; if no breakpoint is set,
control is returned to the client.</p>

<h2>Installation</h2>

<p>This version of cdb has been installed and (lightly) tested on RedHat Linux 2.1,
Solaris 2.5.1, and Windows NT 4.0. Installation involves building cdb, the nub library (<code>libnub.a</code>),
and rebuilding rcc (lcc's compiler proper) and lcc (lcc's compilation driver).</p>

<p>The following steps describe the installation under Solaris and Linux. Similar steps
apply to Windows NT 4.0. Under NT, you'll need a UNIX-style shell and Visual C++ 5.0 or
6.0. 

<ol>
  <li>Install lcc 4.1 (<a href="http://www.cs.princeton.edu/software/lcc/">http://www.cs.princeton.edu/software/lcc/</a>),
    asdlGen 1.2 (<a href="http://sourceforge.net/projects/asdl/">http://sourceforge.net/projects/asdl/</a>),
    and the CII library (<a href="http://www.cs.princeton.edu/software/cii/">http://www.cs.princeton.edu/software/cii/</a>).</li>
  <li>Create a file, <code>custom.mk</code>, that redefines the definitions at the top of the
    makefile to suit your local configuration. Make sure <code>BUILDDIR</code> points to the
    lcc 4.1 build directory (or a copy of it) and <code>ASDL_HOME</code> points to the root of
    the asdlGen installation.</li>
  <li>Edit <a href="etc/solaris.c"><code>etc/solaris.c</code></a>
    or <a href="etc/linux.c"><code>etc/linux.c</code></a>
    (or a copy) to suit your local configuration, and set <code>HOSTNAME</code> to the name of
    the appropriate file in <code>custom.mk</code>. These files are variants of the driver
    back ends included in the lcc 4.1 distribution. They support the -Wo-g4 option, which
    causes lcc to emit cdb-style symbol tables as ASDL pickles.</li>
  <li>Linux doesn't have <code>-lsocket</code> (the socket library), so, if you're running on
    Linux, redefine <code>LIBS</code> in <code>custom.mk</code>; e.g., I use <blockquote>
      <pre>LIBS=-lasdl -lcii -lnsl</pre>
    </blockquote>
  </li>
  <li>Run make: <blockquote>
      <pre>1% make CUSTOM=custom.mk</pre>
    </blockquote>
    <p>You can omit the assignment if your local configuration is in <code>custom.mk</code>. I
    use different names for different platforms, e.g., </p>
    <blockquote>
      <pre>1% make CUSTOM=linux.mk</pre>
    </blockquote>
    <p>Depending on the values of file timestamps, you might have to touch <a
    href="etc/solaris.c"><code>etc/solaris.c</code></a>,
    <a href="etc/linux.c"><code>etc/linux.c</code></a>,
    or <a href="src/inits.c"><code>src/inits.c</code></a>,
    or remove the corresponding object
    files, to force rebuilding of lcc or rcc. <strong>IMPORTANT</strong>: Use the same C
    compiler you used to build lcc.</p>
  </li>
  <li>Copy the startup code to the build directory, e.g.,<blockquote>
      <pre>1% cp startup/solaris.o ${BUILDDIR}/startup.o</pre>
    </blockquote>
    <p>Notice that the name of the installed startup code is always <code>startup.o</code>.</p>
  </li>
  <li>Test the single-process version of cdb by building the sample program:<blockquote>
      <pre>1% make CUSTOM=custom.mk stubtest</pre>
    </blockquote>
    <p>Then run a.out:</p>
    <blockquote>
      <pre>1% a.out
fetching module [1571580302] inhaling lookup.c[1571580302]
fetching module [1571580299] inhaling wf.c[1571580299]
cdb&gt;</pre>
    </blockquote>
    <p>The documentation in &lsquo;A Machine-Independent Debugger&rsquo; applies; the
    &lsquo;h&rsquo; command summarizes the commands.</p>
  </li>
  <li>Test the two-process version of cdb. Build the sample program with<blockquote>
      <pre>1% make CUSTOM=custom.mk test</pre>
    </blockquote>
    <p>Then run cdb:</p>
    <blockquote>
      <pre>1% ${BUILDDIR}/cdb
/u/drh/pkg/4.1/sparc-solaris/cdb listening on 0.0.0.0:9001</pre>
    </blockquote>
    <p>In a separate window, set the <code>DEBUGGER</code> environment variable and run a.out:</p>
    <blockquote>
      <pre>2% setenv DEBUGGER localhost:9001
2% a.out
client: connected on 127.0.0.1:47632 to 127.0.0.1:9001</pre>
    </blockquote>
    <p>In the cdb window, you should see something like:</p>
    <blockquote>
      <pre>/u/drh/pkg/4.1/sparc-solaris/cdb: now serving 127.0.0.1:1428
fetching module [1571576238] inhaling wf.c[1571576238]
fetching module [1571576369] inhaling lookup.c[1571576369]
cdb&gt;</pre>
    </blockquote>
    <p>When you exit the client, cdb waits for another connection.</p>
  </li>
  <li>The command <code>make CUSTOM=custom.mk clean</code>; cleans up.</li>
  <li>(Optional) Add a link to cdb from <code>/usr/local/bin</code>, e.g.,<blockquote>
      <pre>1% ln -s ${BUILDDIR}/cdb /usr/local/bin/cdb</pre>
    </blockquote>
  </li>
</ol>

<h2>Bugs and Suggestions</h2>

<p>Send me email. I can&rsquo;t promise
timely responses or patches, but I intend to keep cdb in sync with lcc. </p>

<hr>

<address>
  <a href="http://drh.home.dyndns.org/">David R. Hanson</a><br>
  $Id: readme.html 137 2007-02-10 20:24:37Z drhanson $ 
</address>
</body>
</html>
